@im-nobsidian/core 0.2.1 → 0.3.1

package/dist/index.d.ts

@@ -395,6 +395,13 @@ interface ProcessorMetadata {
     readonly properties?: Record<string, unknown>;
     readonly preserveMarkers?: PreserveMarker[];
     readonly images?: ImageReference[];
+    /**
+     * 원시 Notion markdown export 가 압축형(펜스 밖 빈 줄 0)이었는지 — orchestrator 가
+     * `notionEnhancedToObsidian` **이전**에 판정해 전달한다. enhanced 변환의
+     * `<empty-block/>`→빈 줄 치환이 끝난 뒤에는 BlockSpacer 가 스스로 판정할 수 없다(D1).
+     * true: 무조건 재간격 / false: 무동작 / 미지정: 내용 기반 휴리스틱 폴백.
+     */
+    readonly notionExportCompact?: boolean;
     readonly [key: string]: unknown;
 }
 interface ConversionContext {
@@ -723,16 +730,33 @@ declare class NotionClient {
     private fetchDatabaseModern;
     getDatabaseTitle(databaseId: string): Promise<string>;
     /**
-     * 발견된 DB 가 **동기화 가능한지**(접근 가능한 data source 가 있는지) 1회 호출로 판별한다.
+     * 발견된 DB 가 **동기화 가능한지**(접근 가능한 data source 가 있는지) 판별한다.
      * 신 모델(2025-09-03)에서 링크드 DB·미공유 데이터 소스·삭제 DB 는 `data_sources` 가
      * 비어, 행 조회(`dataSources.query`)가 404 로 실패하고 그 전에 생성된 빈 폴더/`.base` 만
      * 남긴다. 발견 단계에서 미리 걸러 **빈 폴더/.base 오염 + 매 pull 의 404 노이즈**를 차단한다.
      * 제목은 함께 반환해 호출처가 추가 조회 없이 폴더명을 잡게 한다.
+     *
+     * F25: 원본이 같은 공유 범위에 있으면 linked view 컨테이너도 `data_sources` 가 **채워져**
+     * 온다(실측 — 워크스페이스 8건). 이때 data source 의 parent database 는 원본이므로,
+     * 첫 소스의 parent 가 자신이 아니면 `linkedOriginalDbId` 로 알려 컨테이너가 원본과 같은
+     * 행 집합을 이중 pull(폴더 릴레이 재배치 churn)하는 것을 발견 단계에서 차단한다.
      */
     getDatabaseSyncability(databaseId: string): Promise<{
         title: string;
         queryable: boolean;
+        linkedOriginalDbId?: string;
     }>;
+    /**
+     * linked database view 컨테이너를 원본 DB 로 해소한다.
+     * 컨테이너 자체는 `data_sources` 가 비어 행 조회가 불가능하지만(getDatabaseSyncability
+     * queryable=false), Views API 의 뷰 상세에는 원본 `data_source_id` 가 실리고 그 data source
+     * 의 parent 가 원본 database 다. 해소 실패(뷰 없음/권한 없음/자기참조)는 null — 호출처가
+     * 기존대로 접근 불가 처리한다.
+     */
+    resolveLinkedDatabase(databaseId: string): Promise<{
+        originalDbId: string;
+        viewName: string;
+    } | null>;
     getDatabaseSchema(databaseId: string): Promise<Record<string, {
         id: string;
         type: string;
@@ -797,7 +821,13 @@ declare class NotionClient {
     fetchAllChildrenDeep(blockId: string): Promise<BlockObjectResponse[]>;
     appendChildren(blockId: string, children: unknown[]): Promise<void>;
     deleteBlock(blockId: string): Promise<void>;
+    /** single_part 업로드 상한 (Notion API 규격 20MB) */
+    private static readonly SINGLE_PART_MAX_BYTES;
+    /** multi_part 파트 크기 — 규격상 마지막 파트 제외 5~20MB, 10MB 고정 사용 */
+    private static readonly MULTI_PART_CHUNK_BYTES;
     uploadFile(fileData: Blob, filename: string, contentType: string): Promise<string>;
+    /** 20MB 초과 파일의 multi_part 업로드 — part_number 는 API 규격상 문자열("1"부터) */
+    private uploadFileMultiPart;
     search(params: {
         query?: string;
         filter?: {
@@ -1073,7 +1103,19 @@ declare class SyncOrchestrator {
     private buildDiscoveredDbConfig;
     /** 접근 불가 DB denylist 를 상태 메타에서 로드한다(하이픈 정규화). */
     private loadInaccessibleDbIds;
+    /** linked view 컨테이너 → 원본 DB 매핑을 상태 메타에서 로드한다(nohyph → nohyph). */
+    private loadLinkedDbMap;
     private pullDiscoveredDatabases;
+    /**
+     * pull 산출 md 의 인라인 DB placeholder(`**제목** *(Notion DB)*` + 보존 마커)를
+     * `![[<실제 .base 경로>|제목]]` 임베드로 재작성한다(F22) — folder note 본문에서
+     * DB 가 텍스트 한 줄이 아니라 실제 Bases 뷰로 보이게 하는 마지막 조각. linked view
+     * 컨테이너는 linkedMap 을 거쳐 원본 DB 의 .base 로 향한다. .base 경로는 DatabaseSyncer
+     * 가 실제 기록한 경로(baseFileInfo)가 SSOT — 폴더명과 .base 파일명은 새니타이즈 규칙이
+     * 달라(공백→하이픈 vs 공백 보존) localFolder 로 추측하면 깨진 임베드가 된다(E2E 실측
+     * 91/158건). 최종적으로 .base 실존까지 확인해, 없으면 placeholder 를 마커째 보존한다.
+     */
+    private rewriteDbPlaceholderEmbeds;
     private resolveNotionLinks;
     private ensureDbSchema;
     private pushCreate;
@@ -1134,6 +1176,13 @@ declare class SyncOrchestrator {
     private pushUpdatePage;
     private fetchPageMarkdown;
     private collectInlineDbRefs;
+    /**
+     * 이번 라운드에 기록된 DB row md 를 읽어 본문의 인라인 DB 참조를 수집한다.
+     * row 페이지는 DatabaseSyncer 자체 파이프라인으로 변환돼 fetchPageMarkdown 의
+     * _inlineDbRefs 수집을 타지 않는다 — 디스크에 남은 보존 마커가 유일한 발견 신호다.
+     * 부모 Notion 페이지 id 는 state DB 역조회(getByPath)로 얻는다(row upsert 직후라 항상 존재).
+     */
+    private collectRowInlineRefs;
     private resolveNotionIdWikilinks;
     private extractParentId;
     private resolveBlockToPageId;
@@ -1221,12 +1270,19 @@ declare class ImageHandler {
     constructor(vaultFs: VaultFS, attachmentFolder?: string, notionClient?: NotionClient | undefined, customFetch?: typeof globalThis.fetch, options?: MediaOptions, stateDb?: IStateDB | undefined);
     private get fetchFn();
     downloadImage(url: string, pageTitle: string): Promise<ImageDownloadResult>;
-    downloadAllImages(markdown: string, pageTitle: string): Promise<{
+    private fetchImage;
+    private persistImage;
+    downloadAllImages(markdown: string, pageTitle: string, pageId?: string): Promise<{
         content: string;
         downloads: ImageDownloadResult[];
     }>;
-    uploadLocalImage(localPath: string): Promise<ImageUploadResult>;
-    uploadAndAppendImages(pageId: string, images: ImageReference[]): Promise<ImageUploadResult[]>;
+    uploadLocalImage(localPath: string, noteFolder?: string): Promise<ImageUploadResult>;
+    uploadAndAppendImages(pageId: string, images: ImageReference[], notePath?: string): Promise<ImageUploadResult[]>;
+    /**
+     * 임베드 경로를 볼트 실제 파일로 해석한다(F23). Obsidian 위키링크 임베드는 노트 옆
+     * 파일을 파일명만으로 참조하는 게 관례라, 노트 폴더 → 볼트 루트 → attachments/ 순으로
+     * 시도한다. 폴백은 조용히 진행하고, 전부 실패했을 때만 마지막 오류를 던진다.
+     */
     private readImageFromVault;
     private getContentTypeFromPath;
     downloadAllFiles(markdown: string, pageTitle: string): Promise<{
@@ -1237,6 +1293,16 @@ declare class ImageHandler {
     private downloadFile;
     private isNotionImageUrl;
     private isNotionFileUrl;
+    /**
+     * notion-hosted 파일 URL 하나를 로컬 첨부로 로컬라이즈한다(P3-A).
+     * DB 행의 `files` 속성처럼 본문 밖에 있는 서명 URL 용 — 서명 URL 은 약 1시간 뒤
+     * 만료되어 frontmatter 에 남으면 깨진 링크가 되고, push 로 되밀면 Notion 원본이
+     * external(만료 URL)로 오염된다(실측). notion-hosted 가 아닌 URL(사용자가 넣은
+     * 진짜 외부 링크)은 다운로드 대상이 아니므로 null 을 반환한다.
+     *
+     * @returns 로컬 첨부 경로(`attachments/...`), 다운로드 대상이 아니거나 실패 시 null
+     */
+    localizeNotionFileUrl(url: string, caption: string): Promise<string | null>;
     private guessExtension;
     private guessFileExtension;
 }
@@ -1260,6 +1326,13 @@ declare class FileHandler {
     private readonly sema;
     constructor(vaultFs: VaultFS, notionClient: NotionClient, stateDb: IStateDB, concurrency?: number);
     pushFilesForFolder(folderPageId: string, folderPath: string): Promise<FileUploadResult[]>;
+    /**
+     * 업로드 후보 목록 — 도구 내부 산출물(`.base`/`.notion.json`)은 제외한다.
+     * node 측 VaultFS 는 과거 `.base` 를 워커에서 빼는 식으로 우회했지만, Obsidian
+     * 어댑터는 모든 파일을 반환하므로 플러그인 push 가 사이드카를 Notion 첨부로
+     * 오염시켰다. 소비자인 여기서 일괄 차단해 구현체 간 동작을 통일한다.
+     */
+    private listUploadableFiles;
     pushAllFiles(): Promise<FileUploadResult[]>;
     downloadFileBlock(url: string, filename: string, targetFolder: string): Promise<FileDownloadResult>;
     downloadFileBlocks(blocks: Array<{
@@ -1295,6 +1368,12 @@ interface DatabaseSyncResult {
      * 엉뚱한 행을 골라 정작 바뀐 행의 relation UUID 를 영영 해소하지 못했다(M3). push 경로는 항상 빈 배열.
      */
     writtenPaths: string[];
+    /**
+     * F25: 이 config 가 linked view 컨테이너로 판정된 경우 data source 원본 database id.
+     * 행 처리는 원본 config 에 양보하고 건너뛰었으므로, 호출처(디스커버리 캐시)는 이 config
+     * 를 제거하고 linked 매핑을 기록해야 다음 pull 부터 이중 방문 자체가 사라진다.
+     */
+    linkedOriginalDbId?: string;
 }
 declare class DatabaseSyncer {
     private readonly config;
@@ -1306,10 +1385,28 @@ declare class DatabaseSyncer {
     private readonly propertyMapper;
     private readonly baseFileGenerator;
     private readonly sidecarGenerator;
+    /**
+     * 이번 프로세스가 실제로 기록한 .base 경로/DB 제목 (databaseId nohyph → info).
+     * placeholder 임베드 재작성(F22)의 SSOT — 폴더명(하이픈 새니타이즈)과 .base 파일명
+     * (sanitizeFileName: 공백·점 보존)은 규칙이 달라 localFolder 로 추측한 경로는 깨진
+     * 임베드가 된다. generateBaseFile 은 매 pull 모든 DB 에 대해 실행되므로 pull 종료
+     * 시점에는 성공한 DB 전체가 채워져 있다.
+     */
+    readonly baseFileInfo: Map<string, {
+        basePath: string;
+        title: string;
+    }>;
     constructor(config: Config, stateDb: IStateDB, notionClient: NotionClient, vaultFs: VaultFS, pipeline: ConversionPipeline, imageHandler: ImageHandler);
     pullAll(): Promise<DatabaseSyncResult>;
     pushAll(): Promise<DatabaseSyncResult>;
-    pullDatabase(dbConfig: DatabaseSyncConfig): Promise<DatabaseSyncResult>;
+    pullDatabase(dbConfig: DatabaseSyncConfig, opts?: {
+        /**
+         * F25: database id(하이픈 유무 무관) → 그 DB 행이 사는 로컬 폴더. 디스커버리 캐시가
+         * 아는 DB 만 반환하고 모르면 null. linked view 컨테이너 판정 시 원본 폴더를 아는
+         * 경우에만 행 소유를 양보한다 — 원본이 미발견이면 이 컨테이너가 유일한 접근 통로다.
+         */
+        resolveDbFolder?: (databaseId: string) => string | null;
+    }): Promise<DatabaseSyncResult>;
     private pullDatabaseViews;
     private generateBaseFile;
     /**
@@ -1324,6 +1421,15 @@ declare class DatabaseSyncer {
      * 결정적 직렬화라 동일 DB 상태 → 동일 바이트 → 멱등(drift/churn 0).
      */
     private generateSidecar;
+    /**
+     * DB 행 `files` 속성의 notion-hosted 서명 URL 을 로컬 첨부로 로컬라이즈한다(P3-A).
+     * 서명 URL 은 약 1시간 뒤 만료되어 frontmatter 에 남으면 깨진 링크가 되고, push 로
+     * 되밀면 Notion 원본이 만료 URL 의 external 파일로 오염된다(실측). 다운로드 성공분은
+     * `[[attachments/..]]` 위키링크로 대체한다 — Bases 카드 `image:` 는 위키링크 스칼라를
+     * 렌더하므로 갤러리 커버도 유지된다. 원본 파일명은 raw 속성의 `name` 에서 취한다
+     * (extractValue 는 URL 만 남긴다). 사용자가 넣은 진짜 외부 URL 은 그대로 둔다.
+     */
+    private localizeFileProperties;
     private pullDatabasePage;
     private pushDatabase;
     /**
@@ -1532,11 +1638,32 @@ declare class FrontmatterGenerator implements Processor {
     process(input: ProcessorInput): ProcessorOutput;
 }
 
+/**
+ * 다른 복원기가 소비하지 못하고 실제로 유실된 보존 마커를 재삽입하는 최후 보루.
+ *
+ * 핵심 전제(F28 교훈): DB 에 저장된 startIndex 는 **push 시점 문자열**의 절대
+ * 오프셋이라 pull 산출물에서는 무의미하다 — 프론트매터 앞·단어 한가운데에
+ * 마커를 박아 파일을 파손시켰다. 재삽입은 반드시
+ *   1) 이미 의미적으로 복원된 마커는 건너뛰고(위키링크 → `[[...]]` 존재 등),
+ *   2) 텍스트 앵커(__anchor)를 1차 위치 수단으로 쓰며,
+ *   3) 프론트매터 뒤·줄 경계에만, 마커 단독 줄로 삽입한다.
+ *
+ * 이중 모드: `__anchor` 키가 없는 마커는 구버전 DB blob(수집기가 앵커를 안 남기던
+ * 시절)이다. 이들은 구계약 — "변환이 마커만 제거했다면 startIndex 오프셋 원문 삽입이
+ * 원본을 정확히 재구성한다" — 을 유지하되 프론트매터 앞 삽입만 금지한다. 위해한
+ * 레거시 사례(빈 params 껍데기, 이미 복원된 위키링크)는 render-null 폐기와 의미
+ * 복원 검사가 이미 걸러낸다.
+ */
 declare class PreserveMarkerInjector implements Processor {
     readonly name = "PreserveMarkerInjector";
     readonly order = 100;
     process(input: ProcessorInput): ProcessorOutput;
-    private formatMarker;
+    /** 마커의 본문 표현. 복원 불가능한(빈) 마커는 null — 삽입하지 않고 폐기한다. */
+    private renderMarker;
+    /** 마커가 이미 원래 문법으로 복원돼 있으면 재삽입은 중복·오염이다. */
+    private isSemanticallyRestored;
+    /** 삽입 위치: 앵커 → startIndex(줄 경계 보정) 순. 항상 프론트매터 뒤. */
+    private findInsertionPoint;
 }
 
 declare class LocalImageRestorer implements Processor {
@@ -1756,9 +1883,10 @@ type BasesViewType = "table" | "cards" | "list";
  * Notion 뷰 타입 → Obsidian Bases 뷰 타입 매핑(SSOT).
  *
  * `null` = Bases 에 대응 뷰가 없어 `.base` 로 표현 불가. 이 경우 해당 뷰는 `.base` 에서
- * 누락되므로, 사이드카(`<db>.notion.json`)가 원본 뷰 설정을 무손실 보존한다
- * (Notion API 는 뷰 생성/수정을 지원하지 않아 뷰는 pull-authoritative — push 로 되돌릴 수
- * 없으므로 "조용한 유실 금지"는 곧 "보존 + 정직한 degrade 리포트"를 의미한다).
+ * 누락되므로, 사이드카(`<db>.notion.json`)가 원본 뷰 설정을 무손실 보존한다.
+ * 뷰는 현재 pull-authoritative — Notion API 가 2026-03-19 뷰 생성/수정/삭제를 열었지만
+ * 본 프로젝트는 아직 뷰 write-back 을 구현하지 않았다(로드맵 항목). push 로 되돌릴 수
+ * 없는 동안 "조용한 유실 금지"는 곧 "보존 + 정직한 degrade 리포트"를 의미한다.
  */
 declare const NOTION_TO_BASES_VIEW: Record<string, BasesViewType | null>;
 /** Notion 뷰 타입의 Bases 대응 타입을 돌려준다. 미지원/미상 타입은 `null`. */